html 캡처 라이브러리 비교
작성일 : 2025.04.14
최근 웹 개발에서 HTML 콘텐츠를 PDF나 이미지로 변환하는 기능은 보고서 생성, 명세서 출력, 콘텐츠 공유 등 다양한 용도로 활용되고 있습니다. 하지만 수많은 라이브러리와 도구들 중 어떤 것을 선택해야 할지 결정하는 것은 쉽지 않습니다.
그 중 대표적인 라이브러리는 아래와 같습니다.
- PhantomJS
- html2pdf.js
- pdfmake
- html2canvas + jsPDF 조합
- wkhtmltopdf
- html-to-image / dom-to-image
- Puppeteer
목차
1. 변환 도구별 핵심 특징과 장단점
PhantomJS
기능: 헤드리스 웹 브라우저로, PDF 및 이미지 렌더링 가능한 선구자적 도구
✅ 장점
- JavaScript 및 CSS까지 포함한 실제 브라우저 렌더링 결과 기반 출력
- CLI와 스크립트로 자동화 프로세스 구현 가능
❌ 단점
- 프로젝트가 더 이상 유지보수되지 않음 (deprecated)
- 성능이 느리고 최신 웹 표준 반영이 부족함
html2pdf.js (html2canvas + jsPDF 기반 라이브러리)
기능: 브라우저 환경에서 직접 HTML을 PDF로 변환하여 저장
✅ 장점
- 클라이언트 사이드에서 동작하므로 별도 서버 설치 불필요
- 사용법이 간편하며 기존 웹 프로젝트에 쉽게 통합 가능
❌ 단점
- 복잡한 레이아웃/스타일 미지원 (예: flex, grid 레이아웃, 특수 폰트 등)
- 렌더링 해상도가 낮을 수 있으며, 대규모 문서에서 성능 이슈 발생
pdfmake
기능: JSON 기반 PDF 문서 생성기
✅ 장점
- 동적으로 PDF 문서 구조를 코드 기반으로 정의 가능
- 표, 스타일, 이미지 등 다양한 PDF 요소 지원
❌ 단점
- HTML을 직접 파싱하지 못함 (HTML 변환 시 수동 변환 로직 구현 필요)
- 복잡한 웹 레이아웃을 그대로 재현하기 어려움
html2canvas + jsPDF 조합
기능: DOM 요소를 캡처하여 캔버스 이미지로 생성 후 PDF로 저장
✅ 장점
- 순수 클라이언트 사이드에서 PDF 생성 가능
- 비교적 단순한 구조의 HTML에는 효과적으로 작동
❌ 단점
- 텍스트가 이미지로 변환되어 선택/복사/검색 불가능
- 캡처 정확도가 낮을 수 있음 (스크롤 영역, 동적 콘텐츠 대응 부족)
- PDF 내 이미지 화질 조절에 제한이 있음
wkhtmltopdf
기능: HTML을 PDF로 변환하는 CLI 기반 도구 (WebKit 렌더링 엔진 사용)
✅ 장점
- HTML, CSS 표준을 거의 완벽하게 지원하여 PDF 출력 퀄리티가 우수함
- CLI 기반으로 자동화 시스템에 적합
❌ 단점
- 서버 사이드에서만 동작 가능
- 설치 패키지가 무겁고 환경 구성이 까다로울 수 있음
- JavaScript 실행에 일부 제한이 있어 동적 콘텐츠 처리가 제한적
html-to-image / dom-to-image
기능: HTML 요소를 다양한 포맷의 이미지로 변환 (PNG, JPEG 등)
✅ 장점
- DOM 스냅샷을 정확히 이미지로 캡처하여 단순 보고서에 적합
- 클라이언트 브라우저에서 직접 사용 가능
❌ 단점
- 텍스트가 이미지화되어 검색/복사 불가능
- PDF 형식으로 변환하려면 별도 라이브러리 필요 (예: jsPDF 연동)
Puppeteer
기능: Headless Chrome을 통한 정밀한 PDF/이미지 렌더링
✅ 장점
- 실제 최신 Chrome 브라우저 렌더링 결과를 그대로 출력 (JS, CSS 완벽 지원)
- 스크립트 기반으로 페이지 조작 및 자동화 프로세스 구현 가능
- 최신 웹 기술 완벽 대응 (SPA, 동적 콘텐츠 등 지원)
❌ 단점
- 서버 측 Node.js 환경 에서만 실행 가능
- 리소스 소모가 크고 초기 설치 크기가 큼
2. 서버/클라이언트 측면에서의 비교
서버 사이드 도구
서버에 설치하여 실행하는 방식으로, 사용자 환경과 무관하게 일관된 결과물 제공이 가능합니다.
| 도구 | 실행 환경 | 특징 |
|---|---|---|
| PhantomJS | 서버 | Deprecated, 대체 도구 사용 권장 |
| wkhtmltopdf | 서버 | WebKit 기반, 정적 HTML 변환에 최적화 |
| Puppeteer | Node.js 서버 | Chrome 기반, 동적 콘텐츠 완벽 지원 |
서버 사이드 장점:
- 클라이언트 디바이스 사양과 무관한 일관된 출력
- 백그라운드 작업으로 대용량 문서 처리 가능
- 자동화 시스템에 적합 (예: 정기 보고서 생성)
서버 사이드 단점:
- 서버 리소스 소모
- 설치 및 환경 구성 필요
- 추가 인프라 비용 발생 가능
클라이언트 사이드 도구
사용자 브라우저에서 직접 변환 작업을 수행하는 방식입니다.
| 도구 | 실행 환경 | 특징 |
|---|---|---|
| html2pdf.js | 브라우저 | 간편한 통합, 단순 문서에 적합 |
| pdfmake | 브라우저 | JSON 기반 동적 PDF 생성 |
| html2canvas + jsPDF | 브라우저 | DOM 스크린샷 방식 |
| html-to-image | 브라우저 | 고품질 이미지 캡처 |
클라이언트 사이드 장점:
- 서버 의존성 없음 (API 호출 없이 즉시 변환)
- 사용자 기기에서 처리되어 서버 부하 감소
- 간단한 통합 (JavaScript만으로 구현 가능)
클라이언트 사이드 단점:
- 브라우저/디바이스별 출력 차이 발생 가능
- 대용량 문서 처리 시 사용자 기기에 부담
- 복잡한 레이아웃 처리에 한계
3. 용량 및 호환성 분석
라이브러리 용량 비교
| 도구 | 대략적 용량 | 비고 |
|---|---|---|
| PhantomJS | 약 50~60MB | 서버 설치 용량 |
| html2pdf.js | 약 300~500KB | 클라이언트 번들 크기 |
| pdfmake | 약 1.5MB | 클라이언트 번들 크기 |
| html2canvas + jsPDF | 합산 약 500KB | 클라이언트 번들 크기 |
| wkhtmltopdf | 약 50~100MB | 서버 설치 용량 |
| html-to-image | 약 100~200KB | 클라이언트 번들 크기 |
| Puppeteer | 약 6MB (Chromium 포함 시 100~150MB) | 서버 설치 용량 |
브라우저 호환성 분석
| 도구 | IE | Chrome | Firefox | Safari | Edge | 비고 |
|---|---|---|---|---|---|---|
| html2pdf.js | 제한적 | ✅ | ✅ | ✅ | ✅ | 최신 브라우저 권장 |
| pdfmake | IE 11 제한적 | ✅ | ✅ | ✅ | ✅ | 폰트 지원에 차이 있음 |
| html2canvas | 부분 지원 | ✅ | ✅ | ✅ | ✅ | CSS 지원 범위에 차이 |
| html-to-image | ❌ (ES6 필요) | ✅ | ✅ | ✅ | ✅ | 모던 브라우저만 지원 |
서버 사이드 도구들(PhantomJS, wkhtmltopdf, Puppeteer)은 브라우저 호환성 문제가 없습니다. 서버에서 렌더링 후 결과만 전달하기 때문입니다.
4. CORS 안정 성 분석
웹 애플리케이션에서 HTML을 PDF나 이미지로 변환할 때 CORS(Cross-Origin Resource Sharing) 이슈는 자주 발생하는 문제점입니다. 특히 외부 리소스(이미지, 폰트, CSS, JS 등)가 포함된 HTML을 캡처할 때 더욱 중요한 고려사항이 됩니다.
CORS 이슈가 발생하는 주요 상황
- 외부 이미지 포함: 다른 도메인의 이미지가 HTML에 포함되어 있을 때
- 외부 폰트/스타일시트: CDN이나 다른 도메인에서 호스팅되는 폰트, CSS 파일 사용 시
- iframe 내용 캡처: 다른 도메인의 컨텐츠가 iframe으로 포함되어 있을 때
- API를 통한 데이터 렌더링: 외부 API에서 가져온 데이터로 콘텐츠를 구성할 때
도구별 CORS 안정성 비교
| 도구 | CORS 안정성 | 특징 및 제한사항 |
|---|---|---|
| html2canvas | ⚠️ 제한적 | - 동일 출처 정책 적용됨 - 외부 이미지는 crossorigin="anonymous" 속성 필요- CSS background-image의 외부 리소스 종종 무시됨 |
| html2pdf.js | ⚠️ 제한적 | - html2canvas 기반이므로 동일한 CORS 제한 존재 - 외부 리소스 접근에 제약 있음 |
| html-to-image | ⚠️ 제한적 | - 외부 이미지는 crossorigin 설정 필요- SVG 내부의 외부 리소스 종종 누락됨 - fetch 폴리필이 필요할 수 있음 |
| pdfmake | ✅ 안정적 | - 외부 리소스를 직접 다운로드하는 방식으로 동작 - 서버 프록시와 함께 사용하면 CORS 우회 가능 |
| wkhtmltopdf | ✅✅ 매우 안정적 | - 서버에서 실행되므로 브라우저 CORS 제한 없음 - 모든 리소스 접근 가능 |
| Puppeteer | ✅✅ 매우 안정적 | - 서버에서 실행되므로 브라우저 CORS 제한 없음 - Chrome 옵션으로 CORS 비활성화 가능 - 인증이 필요한 리소스도 쿠키/세션 설정으로 접근 가능 |
CORS 이슈 해결 방법
-
클라이언트 사이드 도구 사용 시:
- 모든 리소스를 동일 도메인에서 제공
- 이미지에
crossorigin="anonymous"속성 추가- 이런 경우, 이미지 서버의 세팅에 따라 이미지가 안 가져오는 경우가 있음
- CDN에 적절한 CORS 헤더 설정 요청
- 외부 리소스를 Base64로 인코딩하여 사용
// html2canvas에서 CORS 설정 예시 html2canvas(document.body, { useCORS: true, // CORS 활성화 allowTaint: false, // 외부 이미지 허용하지 않음 foreignObjectRendering: true // 가능한 경우 foreignObject 렌더링 사용 }); -
서버 사이드 도구 사용 시:
- Puppeteer에서 CORS 비활성화:
const browser = await puppeteer.launch(); const page = await browser.newPage(); // CORS 비활성화 await page.setBypassCSP(true); await page.goto('https://example.com'); await page.pdf({ path: 'output.pdf' });- wkhtmltopdf에서 커스텀 헤더 설정:
wkhtmltopdf --custom-header "Access-Control-Allow-Origin" "*" input.html output.pdf -
프록시 서버 활용:
- 외부 리소스를 프록시 서버를 통해 동일 도메인에서 제공
- 백엔드에서 리소스를 가져와 Base64로 인코딩하여 프론트엔드에 전달
CORS 관점에서의 추천 도구
- 완벽한 CORS 안정성이 필요한 경우: Puppeteer, wkhtmltopdf (서버 사이드)
- 제한된 환경에서 클라이언트만 사용 가능한 경우:
- 간단한 구조: html-to-image + 리소스 최적화
- 복잡한 구조: pdfmake + 서버 프록시
5. 사용 사례별 최적 도구 추천
상황별 추천 도구
| 사용 사례 | 최적 도구 | 대안 |
|---|---|---|
| 브라우저에서 즉시 PDF 다운로드 기능 | html2pdf.js | html2canvas + jsPDF |
| 복잡한 대시보드/차트 포함 보고서 | Puppeteer | wkhtmltopdf |
| 데이터 기반 동적 PDF 생성 | pdfmake | Puppeteer + 템플릿 |
| 단순 스크린샷/이미지 캡처 | html-to-image | html2canvas |
| 대량 자동 보고서 생성 | Puppeteer | wkhtmltopdf |
| SPA/React/Vue 앱 콘텐츠 캡처 | Puppeteer | html-to-image |
| 서버리스 환경에서의 PDF 생성 | html2pdf.js | pdfmake |
특수 요구사항별 추천
| 요구사항 | 추천 도구 | 이유 |
|---|---|---|
| 텍스트 선택/검색 가능한 PDF | Puppeteer, wkhtmltopdf | 실제 PDF 텍스트 레이어 생성 |
| 고화질 이미지 품질 필요 | Puppeteer, html-to-image | 정밀한 렌더링 품질 |
| 헤더/푸터, 페이지 번호 지원 | Puppeteer, wkhtmltopdf | PDF 메타데이터 지원 |
| 대용량 문서 처리 | Puppeteer (서버에서) | 리소스 효율적 처리 |
| 폰트 임베딩 필요 | pdfmake, Puppeteer | 폰트 처리 지원 |
5. 결론 및 선택 가이드
HTML을 PDF나 이미지로 변환하는 도구 선택은 프 로젝트의 성격과 요구사항에 따라 크게 달라집니다. 아래 핵심 질문을 통해 최적의 도구를 선택하세요:
- 클라이언트 vs. 서버: 사용자 브라우저에서 직접 변환이 필요한가, 서버에서 처리해야 하는가?
- 성능 요구사항: 대용량/복잡한 문서를 처리해야 하는가?
- 출력 퀄리티: 정확한 레이아웃과 스타일 재현이 중요한가?
- 동적 콘텐츠: JavaScript로 렌더링되는 동적 콘텐츠가 많은가?
- PDF 기능: 텍스트 선택, 검색, 메타데이터 등의 PDF 기능이 필요한가?
- CORS 요구사항: 외부 리소스(이미지, 폰트, CSS 등)를 많이 사용하는가?
- 보안 요구사항: 인증이 필요한 콘텐츠나 리소스가 포함되어 있는가?
최종 추천 도구 정리
| 라이브러리 | 주 용도 | CORS 안정성 | 추천 대상 |
|---|---|---|---|
| html2pdf.js | 간단한 브라우저 기반 PDF | ⚠️ 제한적 | 프론트엔드에서 간단한 PDF 출력, 동일 도메인 리소스 |
| pdfmake | 코드로 PDF 생성 | ✅ 안정적 | 폼 기반 보고서, 데이터 기반 PDF, API 연동 |
| html2canvas + jsPDF | 스냅샷 PDF | ⚠️ 제한적 | 스타일 단순한 페이지, 동일 도메인 리소스 |
| wkhtmltopdf | 정적인 HTML 고품질 PDF | ✅✅ 매우 안정적 | 서버 기반 보고서, 외부 리소스 포함 문서 |
| Puppeteer | 완전한 브라우저 렌더링 PDF | ✅✅ 매우 안정적 | 복잡한 SPA, 동적 콘텐츠, 인증 필요 리소스 |
| html-to-image | 이미지 변환 | ⚠️ 제한적 | 이미지 기반 보고서, 동일 도메인 리소스 |
결론적으로, HTML → PDF/이미지 변환 도구 선택은 환경과 요구사항에 따라 크게 달라집니다. 클라이언트 측 간단한 기능이면 html2pdf.js나 html-to-image가 적합하고, 고품질 출력이 필요하거나 서버 자동화가 필요하면 Puppeteer가 최선의 선택입니다.